TPUG - Toronto PET Users Group/TPUG Users Group CD/TPUG Users Group CD.iso/AMIGA/(A)C/(A)C1.ADF/Utilities/Lharc.doc

Text File | 1989-09-12 | 28KB | 612 lines

_____________________________________________________________________
---------------------------------------------------------------------

                        LHARC        vers. 1.21

                        for the Commodore AMIGA
         Compatible with version 1.13 of Lharc for MSDOS systems

                  by Paolo Zibetti   (FidoNet 2:331/101.6)
                  (assembler routines by  Paolo Toccaceli)


---------------------------------------------------------------------
 IMPORTANT NOTICE:  This program is copyrighted by Paolo Zibetti, but
can be freely distributed, providing that the following rules are
respected.
 - No change is made to the program nor to the accompaning
documentation
 - The package is always distributed in its complete form consisting
of 3 files: "Lharc", "Lharc.doc" and "Changes".
 - Every form of distribution is allowed and encouraged, but no fee
can be charged for this program exept for, possibly, the cost of
magnetic media and/or disk duplication and shipping.
 - Inclusion in PD software libraries such as Fish Disks is allowed,
   provided the fees charged for theese disks are comparable with
those charged by Fred Fish.
 - The program cannot be distributed in any commercial product
without the written consent of the author.
 By copying, distributing and/or using the program you indicate your
acceptance of the above rules.
 Also remember that this program is supplied 'as is': the entire risk
as to the quality of the program is to the user. In no event will the
author be liable for direct or indirect damage or loss resulting from
the use of this program.
---------------------------------------------------------------------
_____________________________________________________________________


   Introduction ---

Lharc is an archive program such as Arc and Zoo. It can store several
files in one archive in a compressed form which is generally more
efficent than that used by Arc and Zoo.  It also supplies all of the
archive handling capabilities that an archive program should have.
In particular it is able to store an entire directory tree
with one single command. This enables you, for example, to store an
entire floppy-disk with a single command creating an archive which is
usually shorter than those prodeced by Warp or even LhWarp (see the
 -r switch). Another important feature of Lharc is its ability to
preserve the file attributes (see the -a switch) and filenotes (i.e.
the comments that AmigaODS can associate to each file).
Its only weakness is compression speed: Zoo 2.0, for example, is
faster, but if compression efficency is more important for you than
compression time you'll surely appreciate this progam. (anyway
decompression is much faster than compression)





 --- Before starting ---

Lharc is a 'pure' program, i.e. you can make it resident via the
'resident' Amigados command just like any other command found in the
c: directory. Keeping Lharc resident will greatly facilitate users
who make an heavy use of Lharc (especially those who don't have an
hard disk).
If you have just received Lharc, beware that some copy programs and
some archivers (including the zoo archiver which is used for
distribution of Lharc) don't preserve file attributes, so the 'p'
flag may not be set for the Lharc executable and Amigados won't
understand that Lharc is a pure program. If so, just type the
following line at the CLI prompt:

 protect Lharc p add




 --- How to use ---

Lharc is run from CLI with the following command line:

  Lharc [<switches>] <Command> <Archive> [<dest path>] [<file
patterns>]
         items in square brackets are optional.




<Command> can be any of the following (case is not significant):


  e,x  extract files from archive
       Extracts files from archives. If you specify some file names
       or patterns only those files satisfying the patterns are
       extracted, otherwise all the files in the archive are
       extracted.
       While extracting files, Lharc checks if a file by the same
       name already exsists in the destination directory and prompts
       you before overwriting the old file with the extracted one
       (unless you specified the -m switch). By default, if the files
       have a path name stored in the archive, they are extracted
       with their path and needed directories are automatically
       created; use the -x0 switch to ignore path names. See below
       under '<dest path>' for a discussion on where the extracted
       files are stored.

  l    show archives contents
       Displays the names of the files in an archive along with their
       date, time, CRC, compression type, original lenght and
       compressed lenght.
       If the -x switch is specified file names are listed complete
       with their path (if present in the archive), otherwise
       only the name of the files is listed.
       The 'l' command won't list the comments (filenotes) that may
       be associated with a file: use the 'v' command to see them,
       too.

  v    Same as 'l', but default is to display full pathnames: i.e.
       the 'v' command is equivalent to the 'l' command with the -x
       switch; on the other hand the 'l' command is equivalent to the
       'v' command with the -x0 switch. Moreover 'v' will also show
       any filenote (i.e. comment) associated with the files;
       filenotes, if present, are listed on a separate line preceded
       by a colon (i.e. in the same format used by the AmigaDOS
       'list' command).

  p    extract and print files to screen
       same as 'e' and 'x', but extracted files are sent to stdout

  t    test archive integrity
       Checks CRCs and checksums to ensure that the archive is not
       corrupted. Lharc will test all the files on the archive, one
       after each other, printing "OK" to the right of the file names
       which are OK and "WARNING: CRC check failed" to the right of
       file names that are corrupted. At the end of the test the
       message "Operation successful" means that all the files tested
       were OK, while the message "Operation not totally successful"
       means that some files in the archive were corrupted (so you
       will know of a corrupted file even if the warning message
       relating to that file has scrolled away on the screen)

  a    create archives or add to existing archives
       Files are stored in alphabetical order, unless you change
       this with the -S switch. Note however that sorting only
       applies to the files beeing added in the current session,
       i.e. if you add files to an existing archive containing
       other files, the new files will be stored, in alphabetical
       order, AT THE END of the archive: old and new files won't be
       intermixed to preserve global alphabetical order.
       If you try to archive a file and a file by the same name
       already exists in the archive the file will not be added
       and a message will be printed on the screen to inform you.
       By default only file names are stored in the archive, use the
       -x switch to store file names complete with their paths.
       Also, by default file attributes are not stored, use the '-a'
       switch to obtain this.

  m    move files into archivs
       Same as add, but deletes original files after archiving them

  d    delete files from archives
       You can delete from an archive a maximum of 150 files at a
       time, if you find that they are too little, please let me
       know!

  u    update files in archives
       Same as with the 'a' command. However, if a file already
       exists in the archive, LHarc will check its time stamp and
       will keep the newer one and ignore the older one.

  f    freshen files in archives
       Replaces a file in the archive with the newer one only if a
       file with the same name already exists in the archive.
       Otherwise, no action is taken.




<Archive> is the name (eventually preceded by a path) of the
archive you want to work on. If no extension is specified the default
extension .LZH is used.
With the 'l' (or 'v'), 'e' (or 'x'), 'p', 't' and 'a' commands you
can work on multiple archives by using wildcards (see 'file patterns'
below for a list of accepted wildcards). For example "lharc v *.LZH"
will show the contents of all the archives in the current directory,
while "lharc x *.LZH *.c" will extract all the C source files
contained in all the archives in the current directory.



[<dest path>]
This parameter is significant only with the 'x' (or 'e') command and
is ignored otherwise. It tells where to put the extracted files; if
not specified, extracted files will go to the current directory.
Please note that this paramenter must always end with '/' or ':'
otherwise it will not be recognized as such and will be considered
as one of the file patterns.
If the path specified by <dest path> (or equivalently the path stored
in the archive) does not already exist, you will be prompted if you
want new directories to be automatically created (unless you
specified the -m switch, in which case directories will be created
without any prompt).



[<file patterns>] reppresents an optional number of file names
or file patterns. They indicate which files to
extract/compress/list/delete, ecc.
Accepted wild cards are the standard AmigaDOS '#' and '?' plus the
'*' which is a synonim of '#?'. Since however the asterisk is a valid
character in AmigaDOS file names I provided the '**' sequence as an
escape. So if you want to refer to a file name containing an asterisk
just double the asterisk in the file name.
Example:  '*.c' is equivalent to '#?.c' and refers to all the files
ending with '.c', while 'my**file' refers to the file 'my*file'.




[<switches>] rappresents an optional number of switches that are used
to change the behaviour of the program.
A switch is composed by  a leading '-' followed by one letter; unlike
commands which are case insensitive, switches are case sensitive.
An important point is that if you want to specify more than one
switch, every switch must be preceded by its own dash, i.e. to
activate the 'x' and 'm' switches you must enter "-x -m" and NOT
"-xm". You can store your favourite switch configuration in an
environment variable (see below) so that you don't have to type them
every time. All the switches that don't take a parameter can be
followed by a '0' which turns off the function, while the switch
alone or the switch followed by a '1' turns the function on: i.e. -x
means "use extended file names",  while -x0 means "don't use them".
So you can override the default settings or the settings you
specified in the environment variable "LHARC".
Default value for every switch is off, exept for the -x switch which
is by default on with the 'x' 'e' 'd' and 'v' commands and off with
the other  commands.

Here is a summary of the available switches:


  -p  Pause after loading        [note that this is lowercase 'p']
      Causes Lharc to wait for the user to press RETURN before
      executing a command. This allows floppy disk users to swap
      disks after loading Lharc.

  -m  no Message for query
      Suppresses all the queries Lharc normally issues before
      overwriting existing files or before creating new directories
      If you specify this switch Lharc will behave as if you choose
      the default action (indicated by an uppercase letter) in
      response to all the questions. This switch also disables
      autoshowing of files (see 'Autoshow files' below)

  -x  use eXtended file names
      By default, LHarc stores only the file names of files and
      disregards the names of the directories in which they reside.
      This switch, used with the 'a' command, tells LHarc to extend
      all file names with directory names; with the 'x' 'e' 'd'
      and 'v' commands the -x switch is automatically turned on: use
      -x0 if you want to turn it off thus ignoring pathnames with
      these commands.

  -n  No progress indicator
      Suppresses the display of the number of bytes beeing processed
      during compression or decompression. May be useful if you
      redirect to a file the output of Lharc.
      Note: this version of Lharc allows the -N switch as a synonim
      of -n : but this might change in future versions, so preferibly
      use the lowercase letter.

  -w  set Work directory
      Use this switch to choose your own directory for temporary
      files. The directory name must immediatly follow the letter 'w'
      without any leading space, i.e. to set the 'temp' directory on
      your hard-disk as the working directory you must write
      "-wdh0:temp". See below "Temporary files" for a discussion on
      where temporary files are stored in the absence of this switch.

  -P  set Priority          [note that this is uppercase 'P']
      Use this switch to set the priority with which Lharc will be
      executed. Priority must be in the range -5..+5  and must
      immediately follow the 'P' letter without blanks in between.
      By default Lharc is excuted with the same priority of the task
      that invoked it; using this switch will set the new priority
      immediatley after loading and will set back the priority to the
      original value immediately after terminating. If you want to do
      something else with your Amiga, for example editting a letter,
      while Lharc is compressing a long file, I suggest that you set
      Lharc's priority to one less than that of the other program,
      i.e. if you started your editor with the usual priority of zero
      then invoke Lharc with the '-P-1' switch to set its priority to
       -1

  -a  consider file Attributes
      By default Lharc will ignore file attributes (i.e. the flags
      indicating protection from deletion, and so on) for maximum
      compatibility with the MSDOS version: in other words it will
      store files with an attribute bit pattern which is suitable for
      MSDOS machines while during extraction it will ignore the
      attributes stored in the archives, setting the attributes of
      the extracted files to the usual '----rwed'. If you use this
      switch, on the contrary, files will be stored with their
      original attributes and during extraction the stored attribute
      will be restored. Remember that, to effectively preserve file
      attributes, you must use this switch both during compression
      and during extraction. Of course AmigaDOS file attributes are
      meaningless to MSDOS and vice-versa; so extract files with the
      -a switch only if you are sure that they contain AmigaDOS file
      attributes and similarly compress files with the -a switch only
      if you are sure that the archive will be unpacked only by
      Amigas and not by MSDOS machines. (Anyway no harm is done if
      this rule is not respected: extracted files will simply have
      strange attributes)

  -u  convert file names to Uppercase
      By default Lharc stores file names/paths with their original
      case, if you use this switch they will be converted to
      uppercase. See below 'Compatibility' for a possible use of this
      switch.

  -r  Recursively collect files
      This switch instructs Lharc to search for files matching the
      specified patterns not only in the specified directories, but
      also in all the subdirectories that may be found in the
      specified directories. For example: "Lharc -r a archive.lzh
      df1:source/*.c" will search for files whose name ends with ".c"
      in "df1:source/" and in all the subdirectories that may be
      contained in the "df1:source" directory. Another example:
      "Lharc -r a archive.lzh df1:*" will archive the entire disk in
      drive df1:, including all its subdirectories, (you may wish to
      add the -a switch to the above line in order to be able to
      re-build exactly the disk, including file attributes) Very
      powerful, isn't it ? When you specify the -r switch, files are
      always stored with their path name, i.e. the -r switch
      automatically turns on the -x switch, too.

  -S  Set sorting criteria         [note that this is an UPPERCASE S]
      This switch sets the sort criterium for files beeing added to
      archives. The '-S' must be immediatly followed by one or two
      characters, i.e. -Sxy
      'x' can be any of the following:
         0  Don't sort files
         a  Alphabetical sort
         c  Chronological sort
      'y', if present, can be any of the following:
         a  Ascending order
         d  Descending order
      If 'y' is absent, ascending order is assumed by default.
      Examples:
         -Scd          Sort chronologically in descending order
         -Sc  or -Sca  Sort chronologically in ascending order.
         -S0           Don't sort at all
         -Saa          Sort alphabetically in ascending order, this
                       is the default action which is taken if you
                       don't specify this switch.

  -b  Set I/O buffer size
      Big I/O buffers can considerably speed up some operations of
      Lharc (especially with hard disks) however if you are low on
      memory you may prefer to use small I/O buffers. This switch
      lets you set the amount of memory that Lharc will use as an I/O
      buffer: the number of Kbytes of memory to be used must
      immediately follow the 'b' without any spaces in between, e.g.
      -b20 tells Lharc to use 20 kbytes of memory for I/O buffers.
      Any number between 6 and 37 is valid, default is using 11
      Kbytes: if you are low on memory you can lower this amount, but
      if you have plenty of memory I suggest that you raise it. I
      suggest that you set this switch at the value you like in the
      environment variable 'LHARC' (see below) so that you don't have
      to specify this switch every time you invoke Lharc.

  -f  Ignore filenotes
      By defaults Lharc archives files complete with their comment
      (filenote). If you set this switch filenotes won't be stored in
      archives and files beeing extracted won't have their filenote
      even if it's present in the archive. There is no compatibility
      problem, but if you are not interested in filenotes you may set
      this switch to reduce the archive size (filenotes are stored in
      uncompressed form, so if you have long filenotes they can
      increase the size of the archive)





 --- Setting switches in an environment variable ---

   You may set any of LHarc's default switches with the environment
   variable 'LHARC': So, if you, for example, want to always archive
   files with their attributes, use the maximum allowed I/O buffer
   size and use 'dh0:mytemp/' as a working directory you simply type:

   SenEnv LHARC  "-wdh0:mytemp -a -b37"

   (don't forget the quotes): now Lharc will behave as if you typed
   the above switches every time you invoke it. You can insert the
   setenv command in your startup-sequence so that it's automatically
   executed every time you turn your computer on. Of course, you can
   always override the default settings estabilished in the
   enviroment variable with the command line: for example an '-a0' in
   the command line will override the '-a' found in the above
   enviroment variable. Please note that the 'setenv' command is only
   available in Workbench 1.3 and higher: if you are using older
   versions of the O.S. this feature is not available.






 --- Autoshow files ---

Suppose that your archive contains an important text file that you
want to be sure it will be read by the guy who unpacks the archive.
The file may for example contain a copyright notice or some special
instructions for unpacking (if you have packed the archive with the
-a switch you may wish to remind to the one who unpacks the archive
that he/she has to use the -a switch too). For this purpuse this
version of Lharc introduces autoshow files: while unpacking an
archive, if Lharc encounters a file whose name ends with
".TXT.DISPLAYME" (case is not significant and quotes must not be
included, of course), it first extracts the file (removing the
.DISPLAYME extension) and then displays in a window the text found in
that file waiting for the user to press RETURN before proceeding.
You can add as many autoshow files as you want, for example one at
the beginning and one at the end of the archive. Autoshowing of files
is disabled when the -m switch is active so that a non-interactive
unpacking session is allowed. Lharc uses the standard CON: device to
open a window for displaing text, so you can insert ANSI codes in
your autoshow files to make your messages nicer. Lharc will adjust
the size of the window according to the number of lines contained in
the text file, but the maximum allowed size is that of an NTSC screen
(200 pixels), so if your text is longer than 20 lines it will scroll
away. Finally, please note that this feature is unique to the Amiga
version of Lharc (for now...) so remember that if your archive will
be unpacked on another machine (or an an Amiga using Lharc version
1.0 or lower) autoshow files will simply be extracted without
displaying them on the screen; anyway your important text file will
still be there for later reading by the user and no compatibility
problems will arise.





 --- Temporary files ---

While compressing files Lharc creates a temporary file called
'Lharc.TMP_XXXXXX' where XXXXXX is a hex digit representing the
address of its own Task structure as returned by Exec's
FindTask(NULL). The reason for the XXXXXX part of the name is that if
you run multiple copies of Lharc at the same time each copy will
create its own temporary file with a different name (usefull for
multiline BBSes for example). Here is how Lharc decides where to
store temporary files. If you specify a path with the -w switch
temporary files are stored there, otherwise if the T: logical device
is assigned they will be stored in that directory, otherwise they
will go to the current directory. If you are not using the -w switch,
in order to increase compression speed, I reccomend that you assign
T:  to a directory in the ram-disk. Note however that T: is usually
automatically assigned to 'ram:t' in the startup-sequence of the
standard Workbench, so, unless you have modified the
startup-sequence, you don't have to worry about this.






 --- Corrupted archives ---

This version al Lharc for the Amiga has the capability of
automatically handle corrupted archives. A Lharc archive is made up
of several compressed files each precedeed by a header containing
information about file name, date, lenght,... To ensure that the
archive is not corrupted the header also contains a 16 bit CRC of the
file and an 8 bit checksum of the header itself. If during extraction
Lharc finds a corrupted file (i.e. one whose CRC does not match with
the one stored in the header) the file is extracted anyway, but a
warning is printed on the screen. The worst case comes when the
header of a file is corrupted: in this case the file cannot be
extracted even if the file itself is not corrupted. In this case
Lharc will automatically skip the corrupted entry by starting a
search for the next valid entry in the archive and will print a
message like "WARNING: skipping extraneous/corrupted data". The
reason for which it says "extraneous/corrupted" is that an Lharc
archive might happen to contain parts that Lharc cannot recognize as
valid archive entries even it's not corrupted. This happens when you
are extracting files from a self-extracting archive produced by the
MSDOS version of Lharc, since a self-extracting archive contains 8086
extraction code which the Amiga-Lharc sees as extraneous data. The
only extraneous data which is passed without warnings is additional
bytes at the end of an archive: since they are likely to consist of
zero padding due to XMODEM transfer they are totally ignored.







 --- Return codes ---

When Lharc finishes his work, it returns to the operating system one
of 3 possible return codes:

 0  Everything was OK  (the message "Operation successful" is printed
on the screen).
 5  Lharc finished its work, but something went wrong, for example
Lharc encountered a corrupted entry in the archive, but was able to
continue extracting/testing the rest of the archive (the message
Operation not totally succesful" is printed on the screen).
 20 A fatal error occurred and Lharc was unable to continue its work
(an appropriate message explaining the problem is printed on the
sceen)

Thus you can test the succes of operation in your script files by
means of the 'failat' statement and the 'if warn' test.




 --- Bugs ---

No known known bugs remain in this version.




 ---- Compatibility ---

This program is aimed at full compatibility with the MSDOS version
1.13 of Lharc. A few little problems might arise from some file names
that are legal under AmigaDOS, but illegal under MSDOS. As a matter
of facts AmigaDOS allows a wider range of file names (almost every
character in the ASCII set is allowed and file names can be longer
than 8 characters). For the greatest convenience of Amiga users, I
choose not to restrict the file name range to accomplish the MSDOS
rules, but if you expect that your archives will be unpacked on an
MSDOS machine you'd better respect the MSDOS limits. Also note that,
although MSDOS Lharc version 1.13 CAN extract files whose names
contain lowercase letters, its pattern matching functions don't work
properly with lowercase file names. So if you want to extract an
Amiga-created archive on an MSDOS machine by using pattern matching
functions (for example to extract only some files instead of the
whole archive) you have to create the archive on the Amiga with the
-u switch. Finally, to attain 100% compatibility you shuold not use
the '-a' switch (see above in the switch descriptions)

Also note that the MSDOS version of Lharc has the additional
capability of extracting files from archives produced by Larc (a
popular Japanise archive program): this feature will not be
implemented in the Amiga version.




 ---- Acknowledgements ---

First of all I give credit to Haruyasu Yoshizaki for devising such an
efficent compression algorythm as LZHUF. Second, since the source to
the MSDOS version of Lharc is scarcely portable (lots of 8086
assembler ruotines and MSDOS-dependent C functions), I had to rewrite
the program from scratch. Note however that for LZHUF
compression/decompression I have used as a starting point a 'C'
source for an example of single file compression which I found on a
BBS. Although the code has been now remanaged (and partially
rewritten in assembler by Paolo Toccaceli) it nevertheless was
invaluable to me. For sake of correctness I quote here the the header
found on this source:

/*
 * LZHUF.C English version 1.0
 * Based on Japanese version 29-NOV-1988
 * LZSS coded by Haruhiko OKUMURA
 * Adaptive Huffman Coding coded by Haruyasu YOSHIZAKI
 * Edited and translated to English by Kenji RIKITAKE
 */

I whish to thank the above people whose work has been of fundamental
importance for this project. Thanks to Stefan Boberg for suggesting
how to store filenotes in the archive structure that didn't provide
space for them. Many thanks also go to all the people who contributed
with suggestions and bug reports and particularly to Luca Spada for
his invaluable beta testing work.




 --- How to reach me ---

Please send suggestions, comments and bug reports to:

Paolo Zibetti       Fidonet 2:331/101.6

node 2:331/101 (AmnesiA) is also the official distribution node for
Amiga-Lharc: you'll always find the latest version available on this
board. If you are an officially listed FidoNet node you can f'request
the latest version of Lharc with the magic file name AMILHARC.

Amnesia (2:331/101)  phone [phone]  (v32/HST, upto 14400 bps)



For those who don't have access to a FidoNet node, my Fidonet point
can also be reached from Internet/UUCP at the following address:

[e-mail]